.TH PHPKEYLITE 7 2014-04-29 "Copyright Joey Sabey" "PHP Programmer's Manual"
.SH NAME
phpkeylite \- provides oo user permission functionality to php
.\" +------------------+
.\" | CONTENTS SECTION |
.\" +------------------+
.SH CONTENTS
This documentation is divided into a number of sections, each
providing detailed information about an aspect of
.IR phpkeylite .
.br
Sections in this manual are:
.in +2n
.B INTRODUCTION
.br
.B CONFIGURATION
.br
.B CONSTANTS
.br
.B STATIC METHODS
.br
.B INSTANCE METHODS
.br
.B EXCEPTIONS
.br
.\" +----------------------+
.\" | INTRODUCTION SECTION |
.\" +----------------------+
.SH INTRODUCTION
.I phpkeylite
is a PHP module that provides a class
.RB ( Key )
which adds User specific permission functionality to websites using
.IR phpuserlite .
The design (like that of
.IR phpuserlite )
is focussed on concision and ease of installation, configuration & use.
As with
.I phpuserlite
it uses
.I SQLite
throughout to handle the underlying database
.\" +-----------------------+
.\" | CONFIGURATION SECTION |
.\" +-----------------------+
.SH CONFIGURATION
.I phpkeylite
is very light on configuration, having only a handful of config parameters,
the majority of which you will probably not need to ever alter. Config
parameters are (currently) presented as class constants, and include the
following
.\" const Key::KEYS_SCHEMA
.SS KEYS_SCHEMA
This is the
.I SQL
schema that
.I phpkeylite
will use to create the main
.I keys
database table. You will probably not need to alter this
.\" const Key::USERKEYS_SCHEMA
.SS USERKEYS_SCHEMA
This is the
.I SQL
schema that
.I phpkeylite
will use to create the
.I userKeys
database table. You will probably not need to alter this
.\" const Key::USERKEYSINDEX_SCHEMA
.SS USERKEYSINDEX_SCHEMA
This is the
.I SQL
schema that
.I phpkeylite
will use to create the
.I userKeysIndex
database index (which is used to ensure unique
.BR Key => User
pairs). You will probably not need to alter this
.\" +-------------------+
.\" | CONSTANTS SECTION |
.\" +-------------------+
.SH CONSTANTS
.\" const Key::VERSION
.SS VERSION
This constant tracks the version number of
.IR phpkeylite ,
which will either be in the form
.IR x . x . x
.RI ( x . x . x -rc. x " for release candidates)"
or
.IR trunk .
The version numbers represent major, minor and patch revisions.
Significant structural changes are reflected in the major
revision number, security fixes and other internal changes that
won't affect usage in the minor revision number, and bug fixes
in the patch revision number. (Additional information on the
versioning scheme can be found at
.IR http://semver.org )
It is advised you keep your copy of
.I phpkeylite
up to date against the minor & patch revision at all times.
Versions marked with
.I trunk
should not be considered stable, so please attempt to replicate
any bugs with a numbered version of
.IR phpkeylite ,
if at all possible, before submitting them to the bug tracker
.\" A note on flags
.SS Flags
There are a number of constants labelled as
.IR flags ,
namely;
.BR GET_BY_ID " &"
.BR GET_BY_NAME
These constants are for passing to certain methods as flags to
alter the behaviour of the method. Specific usage should be
documented in the section for the method in question
.\" +------------------------+
.\" | STATIC METHODS SECTION |
.\" +------------------------+
.SH STATIC METHODS
The static methods in
.I phpkeylite
are used to add keys to the database, retrieve sets of keys and to setup
and access the database
.\" static function Key::add()
.SS add\fR(\fIname\fR, \fIdescription\fR)
This method adds a new key into the
.I keys
table of the database, provided that
.I name
does not clash with the name of an existing key.
This method has no return value, though may throw a
.I KeyUnavailableNameException
if there is a name conflict
.\" static function Key::getAll()
.SS getAll\fR(\fIuser\fR)
This method returns an array of
.B Key
objects representing either all the keys in the database, or if an optional
.B User
object is passed all the keys which that user holds
.\" static function Key::getDB()
.SS getDB\fR()
This method returns the (current) database being used by
.B Key 
as a
.I PDO
object. Currently this is an alias for \fBUser\fR::\fIgetDB\fR()
so note that the returned database will have foreign keys switched on,
and the
.I PDO::ATTR_ERRMODE
will be set to
.I PDO::ERRMODE_EXCEPTION
as per
.I phpuserlite
.\" static function Key::setupDB()
.SS setupDB\fR()
This method must be called before you attempt to call any other methods or
create any
.B Key
objects. You only need to call this once, unless you delete or move the
database and wish to recreate the database from scratch. The databse file
used will be the same as that used by
.I phpuserlite
so note that if you are using a custom
.B User
configuration file it must be loaded with \fBUser\fR::\fIloadConfig\fR()
before calling this method; see phpuserlite(7) for more details. Also note
that this method automatically calls \fBUser\fr::\fIsetupDB\fR()
.\" +--------------------------+
.\" | INSTANCE METHODS SECTION |
.\" +--------------------------+
.SH INSTANCE METHODS
.\" Key class constructor
.SS Constructor\fR(\fIuid\fR, \fImode\fR)
The class constructor for
.B Key
treats
.I uid
differently depending on the value of
.IR mode ,
which can be one of the flags
.BR GET_BY_ID " or " GET_BY_NAME .
If
.I mode
is set to
.B GET_BY_ID
(the default) then the constructor looks for a key in the
.I keys
table in the database where
.I id
matches
.I uid
and creates a
.B Key
object if it finds one, otherwise it throws a
.BR KeyNoSuchKeyException .
If
.I mode
is set to
.B GET_BY_NAME
then the constructor looks for a key in the
.I keys
table in the database where
.I name
matches
.I uid
and creates a
.B Key
object if it finds one, otherwise it throws a
.BR KeyNoSuchKeyException .
If
.I mode
is not set to either
.BR GET_BY_ID " or " GET_BY_NAME
then a
.B KeyInvalidModeException
will be thrown
.\" public function [key-object]->__toString()
.SS __toString\fR()
This is the
.I magic method
automatically called if a
.B Key
object is used in a string context, such as in an
.I echo
statement. It will return the
.I name
of the key it represents
.\" public function [key-object]->getID()
.SS getID\fR()
This method returns the
.I id
of the key
.\" public function [key-object]->getName()
.SS getID\fR()
This method returns the
.I name
of the key
.\" public function [key-object]->getDescription()
.SS getID\fR()
This method returns the
.I description
of the key
.\" public function [key-object]->getUsers()
.\" public function [key-object]->setName()
.SS setName\fR(\fIname\fR)
This method sets the name of the key to
.IR name ,
provided it does not clash with any name already in the database. If
.I name
clashes with a name already in the database it will throw a
.B KeyUnavailableNameException
.\" public function [key-object]->setDescription()
.SS setDescription\fR(\fIname\fR)
This method sets the description of the key to
.I description
.\" public function [key-object]->give()
.SS give\fR(\fIuser\fR)
This method will grant the
.B Key
to
.IR user .
It will throw a
.I KeyUserAlreadyHasKeyException
if
.I user
already holds the key
.\" public function [key-object]->take()
.SS take\fR(\fIuser\fR)
This method will revoke the
.B Key
from
.I user
.\" public function [key-object]->turn()
.SS turn\fR(\fIuser\fR)
This method will return
.I TRUE
if
.I user
holds this
.BR Key ,
otherwise it will return
.I FALSE
.\" public function [key-object]->remove()
.SS remove\fR()
This method deletes the key's entry from the database
.\" +--------------------+
.\" | EXCEPTIONS SECTION |
.\" +--------------------+
.SH EXCEPTIONS
.\" class KeyInvalidModeException extends DomainException
.SS KeyInvalidModeException
This exception extends
.IR DomainException ,
and is thrown by methods that have a (usually optional) mode argument and are
passed a mode other than those defined
.\" class KeyUnavailableNameException extends RuntimeException
.SS KeyUnavailableNameException
This exception extends
.IR RuntimeException ,
and is thrown by methods that either add keys to the database, or change
the name of those already in the database, if they are passed a name
already in the database
.\" class KeyNoSuchKeyException extends OutOfBoundsException
.SS KeyNoSuchKeyException
This exception extends
.IR OutOfBoundsException ,
and is thrown when an attempt is made to create a new
.B Key 
object from an
.IR id " or " name
that does not exist
.\" class KeyUserAlreadyHasKeyException extends RuntimeException
.SS KeyUserAlreadyHasKeyException
This exception extends
.IR RuntimeException ,
and is thrown when an attempt is made to grant a
.B Key
to a
.B User
that already holds it
